From 02670bc4139a0532ec8159813624362d6c99331e Mon Sep 17 00:00:00 2001 From: Wendell Smith Date: Thu, 18 Jun 2015 11:57:35 -0400 Subject: [PATCH] Moved and expanded project layout --- src/doc/guide.md | 55 ++++++++++++++++++++++++++++++++++----------- src/doc/manifest.md | 30 +++---------------------- 2 files changed, 45 insertions(+), 40 deletions(-) diff --git a/src/doc/guide.md b/src/doc/guide.md index 466b446d1..9e9f5cc55 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -20,8 +20,8 @@ To accomplish this goal, Cargo does four things: You can convert an existing Rust project to use Cargo. You'll have to create a `Cargo.toml` file with all of your dependencies, and move your source files and test files into the places where Cargo expects them to be. See the [manifest -description](manifest.html) and the "Cargo Conventions" section below for more -details. +description](manifest.html) and the [Project Layout](#project-layout) section +below for more details. # Creating A New Project @@ -199,17 +199,46 @@ source = "git+https://github.com/bjz/color-rs.git#bf739419e2d31050615c1ba1a395b4 Now, if `color-rs` gets updated, we will still build with the same revision, until we choose to `cargo update` again. -# Cargo Conventions - -Cargo uses conventions to make it easy to dive into a new Cargo project. Here -are the conventions that Cargo uses: - -* `Cargo.toml` and `Cargo.lock` are stored in the root of your project. -* Source code goes in the `src` directory. -* External tests go in the `tests` directory. -* The default executable file is `src/main.rs`. -* Other executables can be placed in `src/bin/*.rs`. -* The default library file is `src/lib.rs`. +# Project Layout + +Cargo uses conventions for file placement to make it easy to dive into a new +Cargo project. + +`Cargo.toml` is kept in the root directory, as is `Cargo.lock`. + +If your project is an executable, name the main source file `src/main.rs`. If it +is a library, name the main source file `src/lib.rs`. Cargo can create either of +these automatically with `cargo new --bin` or `cargo new`. + +## Optional Components + + * `src/bin/`: Other executables, to be built by default with + `cargo build` + * `examples/`: Examples of usage, built with `cargo test` or `cargo build + --example NAME` + * `tests/`: Integration tests, built and run with `cargo test` + * `benches/`: Benchmarks, built and run with `cargo bench` + +These are explained in more detail in the [manifest +description](manifest.html#examples), but for now, here is an example directory +layout: + +```notrust +Cargo.toml +Cargo.lock +▾ src/ # directory containing source files + lib.rs # the main entry point for libraries and packages + main.rs # the default file for a project producing an executable + *.rs # other modules + ▾ bin/ # (optional) directory containing executables + *.rs +▾ examples/ # (optional) examples of library usage + *.rs +▾ tests/ # (optional) integration tests + *.rs +▾ benches/ # (optional) benchmarks + *.rs +``` # Cargo.toml vs Cargo.lock diff --git a/src/doc/manifest.md b/src/doc/manifest.md index 86a38cfbd..4f3746800 100644 --- a/src/doc/manifest.md +++ b/src/doc/manifest.md @@ -365,35 +365,11 @@ tests and benchmarks. These dependencies are *not* propagated to other packages which depend on this package. -# The Project Layout - -If your project is an executable, name the main source file `src/main.rs`. -If it is a library, name the main source file `src/lib.rs`. - -Cargo will also treat any files located in `src/bin/*.rs` as -executables. - -When you run `cargo build`, Cargo will compile all of these files into -the `target` directory. - -```notrust -▾ src/ # directory containing source files - ▾ bin/ # (optional) directory containing executables - *.rs - lib.rs # the main entry point for libraries and packages - main.rs # the main entry point for projects producing executables -▾ examples/ # (optional) examples - *.rs -▾ tests/ # (optional) integration tests - *.rs -▾ benches/ # (optional) benchmarks - *.rs -``` - # Examples -Files located under `examples` are example uses of the functionality -provided by the library. When compiled, they are placed in the +Files located under `examples` are example uses of the functionality provided by +the library (see [the guide](guide.html#project-layout) for a further +description of standard project layout). When compiled, they are placed in the `target/examples` directory. They must compile as executables (with `main.rs`) and load in the -- 2.30.2